Network Working Group J. Galbraith 
Request for Comments: 4716 VanDyke Software 
Category: Informational R. Thayer 
Canola & Jones 
November 2006 


The Secure Shell (SSH) Public Key File Format 
Status of This Memo 
This memo provides information for the Internet community. It does 
not specify an Internet standard of any kind. Distribution of this 
memo is unlimited. 
Copyright Notice 
Copyright (C) The IETF Trust (2006). 
Abstract 
This document formally documents an existing public key file format 


in use for exchanging public keys between different Secure Shell 
(SSH) implementations. 


In addition, this document defines a standard textual representation 
for SSH public key fingerprints. 
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Les 


Bis 


Introduction 


The SSH protocol supports the use of public/private key pairs in 
order to perform authentication based on public key cryptography. 
However, in order to use public key authentication in the SSH 
protocol, public keys must first be exchanged between client and 
server. 


This document formally describes an existing public key file format 
that can be used with any of the common existing file transfer 
mechanisms in order to exchange public keys. 


The SSH protocol also uses public/private key pairs to authenticate 
the server. In this scenario, it is important to verify that the 
public key provided by the server is indeed the server’s public key. 
This document describes a mechanism for creating a short text string 
that uniquely represents a particular public key, called 
fingerprinting. 


Conventions Used in This Document 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 


Key File Format 


In order to implement public key authentication, SSH implementations 
must share public key files between the client and the server in 
order to interoperate. 


A key file is a text file, containing a sequence of lines. Each line 
in the file MUST NOT be longer than 72 8-bit bytes excluding line 
termination characters. 


1. Line Termination Characters 


Implementations SHOULD generate public key files using their system’s 
local text file representation. 


In the event that public key files are not transferred as text files, 
implementations SHOULD be prepared to read files using any of the 
common line termination sequence, <CR>, <LF>, or <CR><LF>. 
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3.2. Begin and End Markers 


The first line of a conforming key file MUST be a begin marker, which 
is the literal text: 


—--- BEGIN SSH2 PUBLIC KEY ---- 


The last line of a conforming key file MUST be an end marker, which 
is the literal text: 


=--- END SSH2 PUBLIC KEY ---- 
3.3. Key File Header 


The key file header section consists of multiple RFC822-style header 
fields. Each field is a line of the following format: 


Header-tag ’:’ ” ’ Header-value 

The Header-tag MUST NOT be more than 64 8-bit bytes and is case- 
insensitive. The Header-value MUST NOT be more than 1024 8-bit 
bytes. Each line in the header MUST NOT be more than 72 8-bit bytes. 
A line is continued if the last character in the line is a ’\’. If 
the last character of a line is a ’\’, then the logical contents of 
the line are formed by removing the ’\’ and the line termination 


characters, and appending the contents of the next line. 


The Header-tag MUST be encoded in US-ASCII. The Header-value MUST be 
encoded in UTF-8 [RFC3629]. 


A line that is not a continuation line that has no ’:’ in it is the 
first line of the base64-encoded body. (See Section 3.4.) 


The space of header-tags is managed as described in Section 5. 
Compliant implementations MUST ignore headers with unrecognized 
header-tags. Implementations SHOULD preserve such unrecognized 
headers when manipulating the key file. 


3.3.1. Subject Header 


This field is used to store the login-name that the key was generated 
under. For example: 


Subject: user 
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3.3.2. Comment Header 


The comment header contains a user-specified comment. The comment 
SHOULD be displayed when using the key. 


It is suggested that this field default to user@hostname for the user 
and machine used to generate the key. For example: 


Comment: user@example.com 
Currently, common practice is to quote the Header-value of the 
Comment by prefixing and suffixing it with ’"’ characters, and some 


existing implementations fail if these quotation marks are omitted. 


Compliant implementations MUST function correctly if the quotation 
marks are omitted. 


Implementations MAY include the quotation marks. If the first and 
last characters of the Header-value are matching quotation marks, 
implementations SHOULD remove them before using the value. 


3.3.3. Private Use Headers 


Headers with header-tags beginning with "x-" are reserved for private 
use. 


3.4. Public Key File Body 


The body of a public key file is the base64 encoded ([RFC2045]) 
public key data as specified by [RFC4253], Section 6.6: 


string certificate or public key format identifier 
byte[n] key/certificate data 


As with all other lines, each line in the body MUST NOT be longer 
than 72 8-bit bytes excluding line termination characters. 


3.5. Differences with RFC 1421 PEM Formats 
Implementers should take care to notice that while the format is 
superficially similar to those specified by PEM [RFC1421] and OpenPGP 
[RFC2440], it is not identical; most notably: 


o The other specifications use different BEGIN/END delimiters (five 
dashes, no space rather than four dashes and a space). 


o There is no blank line before the start of the base64-encoded 
contents. 
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o There is no Cyclic Redundancy Check (CRC) at the end of the 
base64-encoded block. 


o Header continuation uses a backslash at the end of the continued 
line rather than whitespace at the start of the next line. 


3.6. Examples 


The following are some examples of public key files that are 
compliant (note that the examples all wrap before 72 bytes to meet 
IETF document requirements; however, they are still compliant.) 


=--- BEGIN SSH2 PUBLIC KEY ---- 

Comment: "1024-bit RSA, converted from OpenSSH by me@example.com" 
x-command: /home/me/bin/lock-in-guest.sh 
AAAAB3NzaClyc2EAAAABIWAAAIEA1on8gxCGJJWSRT 4u0rR1 3mUaUkOHRE4RzZxSZ1zRb 
YYFw8pfGesIFoEuVth4HKyF8k1y4mRUnYHP1XNMNMJ11JCEArC2asV8sHf6zSPVffozZ 
5TT4SfsUu/iKy9l1UCCfXzwre4WWZSXXcPff+EHtWshahu3WzBdnGxm5Xoi89zcE= 
-=--- END SSH2 PUBLIC KEY ---- 


=--- BEGIN SSH2 PUBLIC KEY ---- 

Comment: This is my public key for use on Y 

servers which I don't like. 

AAAAB3NzaC1lkc3MAAACBAPY 8ZOHY2yFSJA6XYC9HRWNHxaehvx5wOJ0rzZdzoSOXxbET 
W6ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDAtbl10+Yp7Stxyl1tHnXF1YLfKD1G4T6JYYrdH 
YI140mleg9e4NnCRleaqoZPF 3UGfZia6bXrGTOFf3gJq2e7Yisk/gF+1VAAAAFQDb8D5c 
vwHWTZDPf£X0D2s 9Rd7NBVOQAAATEAIN92+Bb7D4KLYk3 IwRbXblwxXdkPggA4pfdtw9vGt 
J0/RHd+NjB4e01D+0dix6tXwYGN7PKS5R/FXPNwxHPapc j9uLlJn2AWO2dsknf+i/FAA 
vioUPkmdMc0 zuWoSOESSNhVDt X3WdvVcGcBq9cet zrtOKWOocJmJ 8 0qadxTRHt UAAACB 
AN7CY+KKv1gHpRzFwdQm7HK 9bb1LAo2KwaoxXnadFgeptNBOeSXG1v0+JsvphVMBJc9HS 
n24VYtYtsMu74gXviY3ziVucWK33KEb113jugqnF0GD1B3VVmxHLmxnAz 643WK42Z7dLM5 
sY290uezv4Xz2PuMch5VGPP+CDgzCM41oWgV 

-=--- END SSH2 PUBLIC KEY ---- 


=--- BEGIN SSH2 PUBLIC KEY ---- 

Comment: DSA Public Key for use with MyIsp 
AAAAB3NzaC1lkc3MAAACBAPY8ZOHY2yFSJA6XYC9HRWNHxaehvx5wOJ0rzZdzoSOXxbET 
W6ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDAtbl10+Yp7Stxyl1tHnXF1YLfKD1G4T6JYYAH 
YI140mleg9e4NnCRleaqoZPF 3UG£Zia6bXrGTOFf3gJq2e7Yisk/gF+1VAAAAFQDb8D5c 
vwHWTZDPf£X0D2s 9Rd7NBVQAAATEAIN92+Bb7D4KLYk3 IwRbXblwxXdkPggA4pfdtw9vGt 
J0/RHd+NjB4e01D+0dix6tXwYGN7PKS5R/FXPNwxHPapc j9uLlJn2AWO2dsknf+i/FAA 
vioUPkmdMc0 zuWoSOESSNhVDtX3WdvVcGcBq9cet zrtOKWOocJmJ8 0qadxTRHt UAAACB 
AN7CY+KKv1gHpRzFwdQm7HK 9bb1LAo2KwaoXnadFgeptNBOeSXG1v0+JsvphVMBJc9HS 
n24VYtYtsMu7 4qXviYjziVucWKJjJKEb11juqnFOGDIB3VVmxHLmxnAz 643WK42Z7dLM5 
SY290uezv4Xz2PuMch5VGPP+CDqzCM41owgV 

—--- END SSH2 PUBLIC KEY ---- 
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—--- BEGIN SSH2 PUBLIC KEY ---- 

Subject: me 

Comment: 1024-bit rsa, created by me@example.com Mon Jan 15 \ 
08:31:24 2001 
AAAAB3NzZaClyc2EAAAABJOAAATEAiPWx6WM41hHNedGfBpPINPpZ7yKu+tdnn1sSJejgt4 
596k6Y3zGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt /aZZ9wa++0170kr8prgHc4 
sOW6ONUL£DzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaPOL+hM7 zhFNz jFvpaMgJw0= 
=--- END SSH2 PUBLIC KEY ---- 


4. Public Key Fingerprints 


The security of the SSH protocols relies on the verification of 
public host keys. Since public keys tend to be very large, it is 
difficult for a human to verify an entire host key. Even with a 
Public Key Infrastructure (PKI) in place, it is useful to have a 
standard for exchanging short fingerprints of public keys. 


This section formally describes the method of generating public key 
fingerprints that is in common use in the SSH community. 


The fingerprint of a public key consists of the output of the MD5 
message-digest algorithm [RFC1321]. The input to the algorithm is 
the public key data as specified by [RFC4253]. (This is the same 
data that is base64 encoded to form the body of the public key file.) 
The output of the algorithm is presented to the user as a sequence of 
16 octets printed as hexadecimal with lowercase letters and separated 
by colons. 
For example: "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87" 

5. IANA Considerations 
Section 3.3 defines a new namespace of "Header-tags". These are 
US-ASCII strings of maximum length 64 characters and are 


case-insensitive. 


IANA has created and maintains a registry of these header-tags. The 
registry maps each header-tag to a reference defining the header. 


The initial contents of the registry are as follows: 
subject defined in Section 3.3.1 
comment defined in Section 3.3.2 


Header-tags beginning with "x-" are reserved for private use, as 
defined in [RFC2434]. 


Galbraith € Thayer Informational [Page 6] 


RFC 4716 SSH Public Key File Format November 2006 


All other allocations are to be made by IETF consensus, as defined in 
[RFC2434]. 


6. Security Considerations 


The file format described by this document provides no mechanism to 
verify the integrity or otherwise detect tampering with the data 
stored in such files. Given the potential of adversarial tampering 
with this data, system-specific measures (e.g., Access Control Lists, 
UNIX permissions, other Discretionary and/or Mandatory Access 
Controls) SHOULD be used to protect these files. Also, if the 
contents of these files are transferred it SHOULD be done over a 
trusted channel. 


The header data allowed by this file format could contain an 
unlimited range of information. While in many environments the 
information conveyed by this header data may be considered innocuous 
public information, it may constitute a channel through which 
information about a user, a key, or its use may be disclosed 
intentionally or otherwise (e.g., "Comment: Mary E. Jones, 123 Main 
St, Home Phone:..."). The presence and use of this header data 
SHOULD be reviewed by sites that deploy this file format. 


The public key fingerprint method presented here relies on the MD5 
one-way hash function, which is known to have certain weaknesses 
regarding its collision resistance; however, the particular use made 
of MD5 here depends solely on its 2nd-preimage resistance, not on its 
collision resistance. 


MD5 is used here for historical reasons. 
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